---
title: Référence de l'API des images et des ressources
sidebar:
  label: 'astro:assets'
i18nReady: true
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 6
---
import Since from '~/components/Since.astro';
import ReadMore from '~/components/ReadMore.astro';

<p><Since v="3.0.0" /></p>

Astro fournit des composants intégrés et des fonctions d'aide pour optimiser et afficher vos images. Pour des fonctionnalités et des exemples d'utilisation, [consultez notre guide sur les images](/fr/guides/images/).

## Importations depuis `astro:assets`

```js
import { 
  Image,
  Picture,
  getImage,
  inferRemoteSize,
 } from 'astro:assets';
```

### `<Image />`

Le composant `<Image />` optimise et transforme les images.

Ce composant peut également être utilisé pour créer des [images adaptatives](#propriétés-des-images-adaptatives) qui peuvent s'ajuster en fonction de la taille de leur conteneur ou de la taille et de la résolution de l'écran d'un appareil.

```astro title="src/components/MonComposant.astro"
---
// importe le composant Image et l'image
import { Image } from 'astro:assets';
import monImage from "../assets/mon_image.png"; // Image a une résolution de 1600x900
---

<!-- `alt` est obligatoire sur le composant Image -->
<Image src={monImage} alt="Une description de mon image." />
```

```html
<!-- Sortie -->
<!-- L'image est optimisée, les attributs appropriés sont appliqués -->
<img
  src="/_astro/mon_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="Une description de mon image."
/>
```

#### Propriétés d'Image

Le composant `<Image />` accepte les propriétés listées ci-dessous et les [propriétés d'image adaptatives](#propriétés-des-images-adaptatives) en plus de toutes les propriétés acceptées par la balise HTML `<img>`.

##### src (obligatoire)

<p>

**Type :** `ImageMetadata | string | Promise<{ Par défault : ImageMetadata }>`
</p>

Le format de la valeur `src` de votre fichier image dépend de l'emplacement de votre fichier image :

- **Images locales dans `src/`** - vous devez **également importer l'image** en utilisant un chemin de fichier relatif ou configurer et utiliser un [alias d'importation](/fr/guides/imports/#alias). Utilisez ensuite le nom de l'importation comme valeur dans `src` :

  ```astro title="src/pages/index.astro" "monImageImportee" "{monImageImportee}"
  ---
  import { Image } from 'astro:assets';
  import monImageImportee from '../assets/mon-image-locale.png';
  ---
  <Image src={monImageImportee} alt="texte descriptif" />
  ```

- **Images dans le dossier `public/`** -  utilisez le **chemin d'accès au fichier de l'image par rapport au dossier public** :

  ```astro title="src/pages/index.astro" '"/images/mon-image-publique.png"'
  ---
  import { Image } from 'astro:assets';
  ---
  <Image
    src="/images/mon-image-publique.png"
    alt="texte descriptif"
    width="200"
    height="150"
  />
  ```

- **Images distantes** - utilisez l'**URL complète** de l'image comme valeur de propriété :

  ```astro title="src/pages/index.astro" '"https://example.com/image-distante.jpg"'
  ---
  import { Image } from 'astro:assets';
  ---
  <Image
    src="https://example.com/image-distante.jpg"
    alt="texte descriptif"
    width="200"
    height="150"
  />
  ```

##### alt (obligatoire)

<p>

**Type :** `string`
</p>

Utilisez l'attribut `alt` requis pour fournir un [texte alternatif descriptif](https://www.w3.org/WAI/tutorials/images/) pour les images.

Si une image est simplement décorative (c'est-à-dire qu'elle ne contribue pas à la compréhension de la page), définissez `alt=""` pour que les lecteurs d'écran et autres technologies d'assistance sachent qu'il faut ignorer l'image.

##### width et height (obligatoires pour les images dans `public/`)

<p>

**Type :** `number | undefined`
</p>

Ces propriétés définissent les dimensions à utiliser pour l'image.

Lorsqu'un type de mise en page (`layout`) est défini, celles-ci sont automatiquement générées en fonction des dimensions de l'image et, dans la plupart des cas, ne doivent pas être définis manuellement.

Lorsque vous utilisez des images dans leur rapport hauteur/largeur d'origine, `width` et `height` sont facultatives. Ces dimensions peuvent être automatiquement déduites des fichiers image situés dans `src/`. Pour les images distantes, ajoutez [l'attribut `inferSize` défini sur `true`](#infersize) sur les composants `<Image />` ou `<Picture />` ou utilisez [la fonction `inferRemoteSize()`](#inferremotesize).

Cependant, ces deux propriétés sont requises pour les images stockées dans votre dossier `public/` car Astro n'est pas en mesure d'analyser ces fichiers.

##### densities

<p>

**Type :** ``(number | `${number}x`)[] | undefined``<br />
<Since v="3.3.0" />
</p>

Une liste de densités de pixels à générer pour l'image.

L'attribut `densities` n'est pas compatible avec les [images adaptatives](#propriétés-des-images-adaptatives) utilisant une propriété `layout` ou lorsqu'`image.layout` est définie dans la configuration, et sera ignoré s'il est défini.

Si elle est fournie, cette valeur sera utilisée pour générer un attribut `srcset` sur la balise `<img>`. Ne fournissez pas de valeur pour `widths` lorsque vous utilisez cette valeur.

Les densités égales à des largeurs supérieures à celles de l'image d'origine seront ignorées pour éviter de mettre à l'échelle l'image.

```astro title="src/components/MonComposant.astro"
---
import { Image } from 'astro:assets';
import monImage from '../assets/mon_image.png';
---
<Image
  src={monImage}
  width={monImage.width / 2}
  densities={[1.5, 2]}
  alt="Une description de mon image."
/>
```

```html
<!-- Sortie -->
<img
  src="/_astro/mon_image.hash.webp"
  srcset="
    /_astro/mon_image.hash.webp 1.5x
    /_astro/mon_image.hash.webp 2x
  "
  alt="Une description de mon image."
  width="800"
  height="450"
  loading="lazy"
  decoding="async"
/>
```

##### widths

<p>

**Type :** `number[] | undefined`<br />
<Since v="3.3.0" />
</p>

Une liste de largeurs à générer pour l'image.

Si elle est fournie, cette valeur sera utilisée pour générer un attribut `srcset` sur la balise `<img>`. Une [propriété `sizes`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/sizes) doit également être fournie.

Les attributs `widths` et `sizes` seront automatiquement générés pour les images adaptatives à l'aide d'une propriété `layout`. Fournir ces valeurs n'est généralement pas nécessaire, mais peut remplacer les valeurs générées automatiquement.

Ne fournissez pas de valeur pour `densities` lorsque vous utilisez cette valeur. Une seule de ces deux valeurs peut être utilisée pour générer un `srcset`.

Les largeurs supérieures à l'image d'origine seront ignorées pour éviter de mettre à l'échelle l'image.

```astro
---
import { Image } from 'astro:assets';
import monImage from '../assets/mon_image.png'; // La résolution de l'image est de 1600x900
---
<Image
  src={monImage}
  widths={[240, 540, 720, monImage.width]}
  sizes={`(max-width: 360px) 240px, (max-width: 720px) 540px, (max-width: 1600px) 720px, ${monImage.width}px`}
  alt="Une description de mon image."
/>
```

```html
<!-- Sortie -->
<img
  src="/_astro/mon_image.hash.webp"
  srcset="
    /_astro/mon_image.hash.webp 240w,
    /_astro/mon_image.hash.webp 540w,
    /_astro/mon_image.hash.webp 720w,
		/_astro/mon_image.hash.webp 1600w
  "
  sizes="
    (max-width: 360px) 240px,
    (max-width: 720px) 540px,
    (max-width: 1600px) 720px,
    1600px
  "
  alt="Une description de mon image."
  width="1600"
  height="900"
  loading="lazy"
  decoding="async"
/>
```

##### sizes

<p>

**Type :** `string | undefined`<br />
<Since v="3.3.0" />
</p>

Spécifie la largeur de la mise en page de l'image pour chaque valeur d'une liste de conditions de média. Doit être fourni lors de la spécification de largeurs (`widths`).

Les attributs `widths` et `sizes` seront automatiquement générés pour les images adaptatives à l'aide d'une propriété `layout`. Fournir ces valeurs n'est généralement pas nécessaire, mais peut remplacer les valeurs générées automatiquement.

L'attribut `sizes` généré pour les images contraintes (`constrained`) et pleine largeur (`full-width`) suppose que l'image s'affiche presque sur toute la largeur de l'écran lorsque la fenêtre d'affichage est plus petite que la largeur de l'image. Si la différence est significative (par exemple, si l'image est affichée sur plusieurs colonnes sur un petit écran), vous devrez peut-être ajuster manuellement l'attribut `sizes` pour obtenir de meilleurs résultats.


##### format

<p>

**Type :** `ImageOutputFormat | undefined`
</p>

Vous pouvez éventuellement indiquer le [type de fichier image](https://developer.mozilla.org/fr/docs/Web/Media/Formats/Image_types#types_de_fichiers_dimages_communs) de sortie à utiliser.

Par défaut, le composant `<Image />` produira un fichier `.webp`.

##### quality

<p>

**Type :** `ImageQuality | undefined`
</p>

`quality` est une propriété facultative qui peut être :
- un préréglage (`low`, `mid`, `high`, `max`) qui est automatiquement normalisé entre les formats.
- un nombre compris entre `0` et `100` (interprété différemment selon les formats).

##### inferSize

<p>

**Type :** `boolean`<br />
**Par défaut :** `false`<br />
<Since v="4.4.0" />
</p>

Vous permet de définir automatiquement la largeur (`width`) et la hauteur (`height`) d'origine d'une image distante.

Par défaut, cette valeur est définie sur `false` et vous devez spécifier manuellement les deux dimensions de votre image distante.

Ajoutez `inferSize` au composant `<Image />` (ou `inferSize: true` à `getImage()`) pour déduire ces valeurs du contenu de l'image lors de la récupération. Cela est utile si vous ne connaissez pas les dimensions de l'image distante ou si elles peuvent changer :

```astro title="src/components/MonComposant.astro" "inferSize"
---
import { Image } from 'astro:assets';
---
<Image src="https://example.com/cat.png" inferSize alt="Un chat qui dort au soleil." />
```

`inferSize` peut récupérer les dimensions d'une [image distante d'un domaine qui n'a pas été autorisé](/fr/guides/images/#autoriser-les-images-distantes), cependant l'image elle-même restera non traitée.

##### priority

<p>

**Type :** `boolean`<br />
**Par défaut :** `false`<br />
<Since v="5.10.0" />
</p>

Vous permet de définir automatiquement les attributs `loading`, `decoding` et `fetchpriority` sur leurs valeurs optimales pour les images au-dessus de la ligne de flottaison.

```astro title="src/components/MonComposant.astro" "priority"
---
import { Image } from 'astro:assets';
import monImage from '../assets/mon_image.png';
---
<Image src={monImage} priority alt="Une description de mon image" />
```

Lorsque `priority="true"` (ou la syntaxe abrégée `priority`) est ajouté au composant `<Image />` ou `<Picture />`, les attributs suivants sont ajoutés pour indiquer au navigateur de charger l'image immédiatement :

```html
loading="eager"
decoding="sync"
fetchpriority="high"
```

Ces attributs individuels peuvent toujours être définis manuellement si vous devez les personnaliser davantage.

### `<Picture />`

<p><Since v="3.3.0" /></p>

Le composant `<Picture />` génère une image optimisée avec plusieurs formats et/ou tailles.

Ce composant peut également être utilisé pour créer des [images adaptatives](#propriétés-des-images-adaptatives) qui peuvent s'ajuster en fonction de la taille de leur conteneur ou de la taille et de la résolution de l'écran d'un appareil.

```astro title="src/pages/index.astro"
---
import { Picture } from 'astro:assets';
import monImage from "../assets/mon_image.png"; // La résolution de l'image est de 1600x900
---

<!-- `alt` est obligatoire sur le composant Picture -->
<Picture src={monImage} formats={['avif', 'webp']} alt="Une description de mon image." />
```

```html
<!-- Sortie -->
<picture>
  <source srcset="/_astro/mon_image.hash.avif" type="image/avif" />
  <source srcset="/_astro/mon_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/mon_image.hash.png"
    width="1600"
    height="900"
    decoding="async"
    loading="lazy"
    alt="Une description de mon image."
  />
</picture>
```

#### Propriétés de Picture

`<Picture />` accepte toutes les propriétés du [composant `<Image />`](#propriétés-dimage), y compris les [propriétés d'image adaptatives](#propriétés-des-images-adaptatives), en plus des suivantes :

##### `formats`

<p>

**Type :** `ImageOutputFormat[]`
</p>

Un tableau de formats d'image à utiliser pour les balises `<source>`. Les entrées seront ajoutées en tant qu'éléments `<source>` dans l'ordre dans lequel elles sont répertoriées, et cet ordre détermine le format affiché. Pour de meilleures performances, indiquez d'abord le format le plus moderne (par exemple `webp` ou `avif`). Par défaut, ce paramètre est défini sur `['webp']`.

##### `fallbackFormat`

<p>

**Type :** `ImageOutputFormat`
</p>

Format à utiliser comme valeur de secours pour la balise `<img>`. La valeur par défaut est `.png` pour les images statiques (ou `.jpg` si l'image est au format JPG), `.gif` pour les images animées et `.svg` pour les fichiers SVG.

##### `pictureAttributes`

<p>

**Type :** `HTMLAttributes<'picture'>`
</p>

Un objet d'attributs à ajouter à la balise `<picture>`.

Utilisez cette propriété pour appliquer des attributs à l'élément externe `<picture>` lui-même. Les attributs appliqués directement au composant `<Picture />` s'appliqueront à l'élément interne `<img>`, à l'exception de ceux utilisés pour la transformation d'image.

```astro title="src/components/MonComposant.astro"
---
import { Picture } from "astro:assets";
import monImage from "../mon_image.png"; // La résolution de l'image est de 1600x900
---

<Picture
  src={monImage}
  alt="Une description de mon image."
  pictureAttributes={{ style: "background-color: red;" }}
/>
```

```html
<!-- Sortie -->
<picture style="background-color: red;">
  <source srcset="/_astro/mon_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/mon_image.hash.png"
    alt="Une description de mon image."
    width="1600"
    height="900"
    loading="lazy"
    decoding="async"
  />
</picture>
```

### Propriétés des images adaptatives

La définition de la propriété [`layout`](#layout) sur un composant [`<Image />`](#image-) ou [`<Picture />`](#picture-) crée une image adaptative et active des paramètres de propriété supplémentaires.

```astro title=MonComposant.astro
---
import { Image } from 'astro:assets';
import monImage from '../assets/mon_image.png';
---
<Image src={monImage} alt="Une description de mon image." layout='constrained' width={800} height={600} />
```

 Lorsqu'une mise en page est définie, les attributs `srcset` et `sizes` sont automatiquement générés en fonction des dimensions de l'image et du type de mise en page. Le composant `<Image />` précédent générera la sortie HTML suivante :

```html
<img
  src="/_astro/mon_image.hash3.webp"
  srcset="/_astro/mon_image.hash1.webp 640w,
      /_astro/mon_image.hash2.webp 750w,
      /_astro/mon_image.hash3.webp 800w,
      /_astro/mon_image.hash4.webp 828w,
      /_astro/mon_image.hash5.webp 1080w,
      /_astro/mon_image.hash6.webp 1280w,
      /_astro/mon_image.hash7.webp 1600w"
  alt="Une description de mon image"
  sizes="(min-width: 800px) 800px, 100vw"
  loading="lazy"
  decoding="async"
  fetchpriority="auto"
  width="800"
  height="600"
  style="--fit: cover; --pos: center;"
  data-astro-image="constrained"
>
```
La valeur de `layout` définit également les styles par défaut appliqués à la balise `<img>` pour déterminer comment l'image doit être redimensionnée en fonction de son conteneur :

```css title="Styles des images adaptatives"
:where([data-astro-image]) {
	object-fit: var(--fit);
	object-position: var(--pos);
}
:where([data-astro-image='full-width']) {
	width: 100%;
}
:where([data-astro-image='constrained']) {
	max-width: 100%;
}
```

Vous pouvez remplacer les styles par défaut `object-fit` et `object-position` en définissant les props [`fit`](#fit) et [`position`](#position) sur le composant `<Image />` ou `<Picture />`.


##### layout

<p>

**Type :** `'constrained' | 'full-width' | 'fixed' | 'none'` <br />
**Par défault :** `image.layout | 'none'` <br />
<Since v="5.10.0" />
</p>

Définit une [image adaptative](#propriétés-des-images-adaptatives) et détermine son redimensionnement lorsque son conteneur change de taille. Peut être utilisé pour remplacer la valeur par défaut configurée pour [`image.layout`](/fr/reference/configuration-reference/#imagelayout).

- `constrained` - L'image sera réduite pour s'adapter au conteneur, en conservant son rapport hauteur/largeur, mais ne sera pas agrandie au-delà de la largeur (`width`) et de la hauteur (`height`) spécifiées, ou des dimensions d'origine de l'image.

  Utilisez cette option si vous souhaitez que l'image s'affiche à la taille souhaitée, si possible, mais qu'elle soit réduite pour s'adapter aux écrans plus petits. Cela correspond au comportement par défaut des images avec Tailwind. En cas de doute, c'est probablement la mise en page à choisir.

- `full-width` - L'image sera mise à l'échelle pour s'adapter à la largeur du conteneur, en conservant son rapport hauteur/largeur.

  Utilisez ceci pour les images de couverture ou d’autres images qui doivent occuper toute la largeur de la page.

- `fixed` - L'image conservera les dimensions demandées et ne sera pas redimensionnée. Un `srcset` sera généré pour prendre en charge les affichages haute densité, mais pas pour les différentes tailles d'écran.

  Utilisez cette option si l'image ne peut pas être redimensionnée, par exemple des icônes ou des logos plus petits que la largeur de l'écran, ou d'autres images dans un conteneur à largeur fixe.

- `none` - L'image ne sera pas adaptative. Aucun attribut `srcset` ou `sizes` ne sera généré automatiquement et aucun style ne sera appliqué.

  Ceci est utile si vous avez activé une mise en page par défaut, mais que vous souhaitez la désactiver pour une image spécifique.

Par exemple, avec la valeur `constrained` définie comme mise en page par défaut, vous pouvez remplacer la propriété `layout` de n'importe quelle image individuelle :

```astro title="src/components/MonComposant.astro"
---
import { Image } from 'astro:assets';
import monImage from '../assets/mon_image.png';
---
<Image src={monImage} alt="Cela utilisera une mise en page contrainte" width={800} height={600} />
<Image src={monImage} alt="Cela utilisera une mise en page pleine largeur" layout="full-width" />
<Image src={monImage} alt="Cela désactivera les images adaptatives" layout="none" />
```

##### fit

<p>

**Type :** `'contain' | 'cover' | 'fill' | 'none' | 'scale-down'` <br />
**Par défault :** `image.objectFit | 'cover'` <br />
<Since v="5.10.0" />
</p>

Activée lorsque la propriété [`layout`](#layout) est définie ou configurée. Définit comment une image adaptative doit être recadrée si son rapport hauteur/largeur est modifié.

Les valeurs correspondent à celles de la propriété CSS `object-fit`. La valeur par défaut est `cover` ou la valeur de [`image.objectFit`](/fr/reference/configuration-reference/#imageobjectfit) si elle est définie. Peut être utilisée pour remplacer les styles par défaut de `object-fit`.

##### position

<p>

**Type :** `string` <br />
**Par défault :** `image.objectPosition | 'center'` <br />
<Since v="5.10.0" />
</p>

Activée lorsque la propriété [`layout`](#layout) est définie ou configurée. Définit la position du recadrage de l'image pour une image adaptative si le rapport hauteur/largeur est modifié.

Les valeurs correspondent à celles de la propriété CSS `object-position`. La valeur par défaut est `center` ou la valeur de [`image.objectPosition`](/fr/reference/configuration-reference/#imageobjectposition) si elle est définie. Peut être utilisée pour remplacer les styles par défaut de la propriété `object-position`.

### `getImage()`

<p>

**Type :** `(options: UnresolvedImageTransform) => Promise<GetImageResult>`
</p>

:::caution
`getImage()` s'appuie sur des API serveur uniquement et interrompt la génération lorsqu'elle est utilisée sur le client.
:::

La fonction `getImage()` est prévue pour générer des images destinées à être utilisées ailleurs que directement en HTML, par exemple dans une [route d'API](/fr/guides/endpoints/#points-de-terminaison-du-serveur-routes-api). Elle vous permet également de créer votre propre composant `<Image />` personnalisé.

`getImage()` prend un objet d'options avec les [mêmes propriétés que le composant Image](#propriétés-dimage) (à l'exception de `alt`).

```astro
---
import { getImage } from "astro:assets";
import myBackground from "../background.png"

const optimizedBackground = await getImage({src: myBackground, format: 'avif'})
---

<div style={`background-image: url(${optimizedBackground.src});`}></div>
```

Elle renvoie un objet avec le type suivant :

```ts
type GetImageResult = {
  /* Attributs HTML supplémentaires nécessaires au rendu de l'image (largeur, hauteur, style, etc.) */
  attributes: Record<string, any>;
  /* Paramètres passés validés */
  options: ImageTransform;
  /* Paramètres d'origine transmis */
  rawOptions: ImageTransform;
  /* Chemin d'accès à l'image générée */
  src: string;
  srcSet: {
    /* Valeurs générées pour srcset, chaque entrée a une URL et un descripteur de taille */
    values: SrcSetValue[];
    /* Une valeur prête à être utilisée dans l'attribut `srcset` */
    attribute: string;
  };
}
```

### inferRemoteSize()

<p>

**Type :** `(url: string) => Promise<Omit<ImageMetadata, 'src' | 'fsPath'>>`<br />
<Since v="4.12.0" />
</p>

Une fonction permettant de déduire les dimensions des images distantes. Elle peut être utilisée comme alternative à la transmission de la propriété `inferSize`.

```ts
import { inferRemoteSize } from 'astro:assets';
const {width, height} = await inferRemoteSize("https://example.com/cat.png");
```
